
\section{Style Options}
\label{sec:styles}


\subsection{All Supported Styles}

\PGFPlots{} provides many styles to customize its appearance and behavior. They
can be defined and changed in any place where keys are allowed. Furthermore,
own styles are defined easily.

\begin{handler}{{.style}=\marg{key-value-list}}
    Defines or redefines a style \meta{key}. A style is a normal key which will
    set all options in \meta{key-value-list} when it is set.

    Use |\pgfplotsset{|\meta{key}|/.style={|\meta{key-value-list}|}}| to
    (re)define a style \meta{key} in the namespace |/pgfplots|.
\end{handler}

\begin{handler}{{.append style}=\marg{key-value-list}}
    Appends \meta{key-value-list} to an already existing style \meta{key}. This
    is the preferred method to change the predefined styles: if you only
    append, you maintain compatibility with future versions.

    Use |\pgfplotsset{|\meta{key}|/.append style={|\meta{key-value-list}|}}| to
    append \meta{key-value-list} to the style \meta{key}. This will assume the
    prefix |/pgfplots|.
\end{handler}


\subsection*{Styles installed for linear/logarithmic axis}

\begin{stylekey}{/pgfplots/every axis (initially empty)}
    Installed at the beginning of every axis. \Tikz{} options inside of it will
    be used for anything inside of the axis rectangle and any axis
    descriptions.
\end{stylekey}

\begin{stylekey}{/pgfplots/every axis post (initially empty)}
   A style which is applied right \emph{after} arguments provided to an axis
   are processed.

   In the following example, such a style is used to override the |xmin| and
   |xmax| options provided as arguments to |\begin{axis}[...]|:
   %
\begin{codeexample}[code only]
\begin{tikzpicture}
    \pgfplotsset{
        every axis post/.style={
            xmin=0,xmax=1,
        },
    }
    \begin{axis}[
        xmin=-1,xmax=2,
        ymin=0,ymax=1,
    ]
        ...
    \end{axis}
\end{tikzpicture}
\end{codeexample}

    It is processed right after the arguments of |\begin{axis}|, but before
    styles like |yticklabel style| etc.\@ are evaluated.
\end{stylekey}

\begin{stylekey}{/pgfplots/every semilogx axis (initially empty)}
    Installed at the beginning of every plot with logarithmic $x$-axis and
    linear $y$-axis, but after `|every axis|'.
\end{stylekey}

\begin{stylekey}{/pgfplots/every semilogy axis (initially empty)}
    Likewise, but with interchanged roles for $x$ and $y$.
\end{stylekey}

\begin{stylekey}{/pgfplots/every loglog axis (initially empty)}
    Installed at the beginning of every log--log plot.
\end{stylekey}

\begin{stylekey}{/pgfplots/every linear axis (initially empty)}
    Installed at the beginning of every plot with normal axis scaling.
\end{stylekey}


\subsection*{Styles installed for single plots}

\begin{stylekey}{/pgfplots/every axis plot (initially empty)}
    Installed for each plot. This style may contain options like samples,
    gnuplot parameters, error bars and it may contain options which affect the
    final drawing commands.
\end{stylekey}

\begin{stylekey}{/pgfplots/every axis plot post (initially empty)}
    This style is similar to |every axis plot| in that is applies to any
    drawing command in |\addplot|. However, it is set \emph{after} any user
    defined styles or |cycle list| options.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\pgfplotsset{
    every axis plot post/.append style={mark=none},
}
\begin{axis}[
    legend pos=north west,
    domain=0:1,
]
    \addplot {x^2};
    \addplot {exp(x)};
    \legend{$x^2$,$e^x$}
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{stylekey}

\begin{stylekey}{/pgfplots/every axis plot no \# (initially empty)}
    Used for every \#th plot where $\#=0,1,2,3,4,\dotsc$.

    This style is installed before the argument list of
    |\addplot|\meta{options}, i.e.{} \meta{options} are preferred. Note that
    this also means that any items in a |cycle list| have higher priority.
\end{stylekey}

\begin{stylekey}{/pgfplots/every forget plot (initially empty)}
    Used for every plot which has |forget plot| activated.
\end{stylekey}

\pgfplotsshortstylekey forget plot style=every forget plot\pgfeov


\subsection*{Styles for axis descriptions}

\begin{stylekey}{/pgfplots/every axis label (initially empty)}
    Used for all axis label (like |xlabel| and |ylabel|).
\end{stylekey}

\pgfplotsshortstylekey label style=every axis label\pgfeov

\begin{xystylekey}{/pgfplots/every axis \x\ label}
    Used only for $x$, $y$, or $z$ labels, respectively and installed after
    `|every axis label|'.

    The initial settings are set by |xlabel absolute| and its variants (if the
    initial configuration |compat=pre 1.3| is active) or |xlabel near ticks|
    which provides the better spacing as it incorporates the tick label sizes
    to compute the position.


    \paragraph{Attention:}

    These styles will be overwritten by |axis x line| and/or |axis y line|.
    Please remember to place your modifications after the axis line variations.
\end{xystylekey}

\pgfplotsshortxystylekeys \x\ label style,\x label style=every axis \x\ label\pgfeov

\begin{stylekey}{/pgfplots/every axis title}
    Used for any axis title. The |at=|\parg{x,y} syntax will place the title
    using |axis description cs|.

    The initial setting is
    %
\begin{codeexample}[code only]
\pgfplotsset{every axis title/.style={at={(0.5,1)},above,yshift=6pt}}
\end{codeexample}

    To be more precise, the |yshift| doesn't use the hardcoded |6pt|: it uses
    the value of

    \begin{key}{/pgfplots/every axis title shift=\marg{default shift} (initially 6pt)}
    \end{key}

    which can be reset if needed.
\end{stylekey}

\pgfplotsshortstylekey title style=every axis title\pgfeov

\begin{stylekey}{/pgfplots/every axis legend}
    Installed for each legend. As described for |axis description cs|, the
    legend's position can be placed using coordinates between $0$ and $1$ (it
    employs |axis description cs| automatically).

    The initial setting is
    %
\begin{codeexample}[code only]
\pgfplotsset{
    every axis legend/.style={
        cells={anchor=center},
        inner xsep=3pt,inner ysep=2pt,
        nodes={inner sep=2pt,text depth=0.15em},
        anchor=north east,
        shape=rectangle,
        fill=white,draw=black,
        at={(0.98,0.98)},
    },
}
\end{codeexample}
\end{stylekey}

\pgfplotsshortstylekey legend style=every axis legend\pgfeov

\begin{stylekey}{/pgfplots/every legend image post}
    Allows to change the appearance of the small legend images \emph{after} the
    options of the plot style have been applied. Thus, legend formatting can be
    changed independently of the plot style using |every legend image post|.

    This key is also documented on page~\pageref{key:legendimagepost}.
\end{stylekey}

\pgfplotsshortstylekey legend image post style=every legend image post\pgfeov

\begin{stylekey}{/pgfplots/every legend to name picture}
    A style for use with |legend to image|, see the documentation therein.
\end{stylekey}

\begin{stylekey}{/pgfplots/every colorbar}
    A style to change the |colorbar|. See page~\pageref{key:every:colorbar} for
    the reference documentation of |every colorbar|.
\end{stylekey}

\pgfplotsshortstylekey colorbar style=every colorbar\pgfeov

\subsection*{Styles for axis lines}
\begin{xystylekey}{/pgfplots/every outer \x\ axis line (initially empty)}
    Installed for every axis line which lies on the outer box.

    If you want arrow heads, you may also need to check the
    |separate axis lines| boolean key.
\end{xystylekey}

\begin{xystylekey}{/pgfplots/every inner \x\ axis line (initially empty)}
    Installed for every axis line which is drawn using the |center| or |middle|
    options.
\end{xystylekey}

\begin{pgfplotsxykeylist}{%
    axis line style=\marg{key-value-list},
    inner axis line style=\marg{key-value-list},
    outer axis line style=\marg{key-value-list},
    \x\ axis line style=\marg{key-value-list}%
}
    These options modify parts of the axis line styles. They append options to
    |every inner x axis line| and |every outer x axis line| and the respective
    $y$/$z$ variants.
\end{pgfplotsxykeylist}

\noindent Please refer to Section~\ref{pgfplots:page:axislines} on
page~\pageref{pgfplots:page:axislines} for details about styles for axis lines.

\begin{stylekey}{/pgfplots/every 3d box foreground}
    Installed for the parts drawn by |3d box=complete|. This affects axis
    lines, tick lines and grid lines drawn in the \emph{foreground}. The
    background drawing operations have already been done when this style is
    evaluated.
\end{stylekey}

\pgfplotsshortstylekey 3d box foreground style=every 3d box foreground\pgfeov

\begin{stylekey}{/pgfplots/every colorbar sampled line}
    To be used in conjunction with |colorbar sampled line|, see the
    documentation therein.
\end{stylekey}

\pgfplotsshortstylekey colorbar sampled line style=every colorbar sampled line\pgfeov


\subsection*{Styles for ticks}

\begin{stylekey}{/pgfplots/every tick (initially very thin,gray)}
    Installed for each of the small tick \emph{lines}.
\end{stylekey}

\pgfplotsshortstylekey tick style=every tick\pgfeov

\begin{stylekey}{/pgfplots/every minor tick (initially empty)}
    Used for each minor tick line, installed after `|every tick|'.
\end{stylekey}

\pgfplotsshortstylekey minor tick style=every minor tick\pgfeov

\begin{stylekey}{/pgfplots/every major tick (initially empty)}
    Used for each major tick line, installed after `|every tick|'.
\end{stylekey}

\pgfplotsshortstylekey major tick style=every major tick\pgfeov

\begin{stylekey}{/pgfplots/every tick label (initially empty)}
    Used for each $x$~and~$y$ tick labels.
\end{stylekey}

\pgfplotsshortxystylekeys tick label style,ticklabel style=every tick label\pgfeov

\begin{xystylekey}{/pgfplots/every \x\ tick label (initially empty)}
    Used for each $x$ (or $y$ or $z$, respectively) tick label, installed after
    `|every tick label|'.
\end{xystylekey}

\pgfplotsshortxystylekeys \x\ tick label style,\x ticklabel style=every \x\ tick label\pgfeov

\begin{xystylekey}{/pgfplots/every \x\ tick scale label}
    Configures placement and display of the nodes containing the order of
    magnitude of tick labels, see Section~\ref{sec:scaled:ticks} for more
    information about |scaled ticks|.

    The initial settings with |compat=1.8| or higher are
    %
\begin{codeexample}[code only]
\pgfplotsset{
    every x tick scale label/.style={
        at={(xticklabel cs:0.9,5pt)},
        anchor=near xticklabel,
        inner sep=0pt,
    },
    every y tick scale label/.style={
        at={(yticklabel* cs:1.03,-0.3em)},
        /pgfplots/near ticklabel align=outside,
        anchor=near yticklabel opposite,
        inner sep=0pt,
    },
    every z tick scale label/.style={
        at={(zticklabel* cs:1.2,-0.3em)},
        anchor=near zticklabel,
        inner sep=0pt,
    },
}
\end{codeexample}
\end{xystylekey}

\pgfplotsshortxystylekey \x\ tick scale label style=every \x\ tick scale label\pgfeov

\begin{xystylekey}{/pgfplots/every \x\ tick (initially empty)}
    Installed for tick \emph{lines} on either $x$- or $y$-axis.
\end{xystylekey}

\pgfplotsshortxystylekey \x tick style=every \x\ tick\pgfeov

\begin{xystylekey}{/pgfplots/every minor \x\ tick (initially empty)}
    Installed for minor tick lines on either $x$- or $y$-axis.
\end{xystylekey}

\pgfplotsshortxystylekey minor \x\ tick style=every minor \x\ tick\pgfeov

\begin{xystylekey}{/pgfplots/every major \x\ tick (initially empty)}
    Installed for major tick lines on either $x$- or $y$-axis.
\end{xystylekey}
\pgfplotsshortxystylekey major \x\ tick style=every major \x\ tick\pgfeov

\begin{xystylekey}{/pgfplots/every extra \x\ tick}
    Allows to configure the appearance of `|extra x ticks|'. This style is
    installed before touching the first extra $x$~tick. It is possible to set
    any option which affects tick or grid line generation.

    The initial setting is
    %
\begin{codeexample}[code only]
\pgfplotsset{
    every extra x tick/.style={/pgfplots/log identify minor tick positions=true},
    every extra y tick/.style={/pgfplots/log identify minor tick positions=true},
}
\end{codeexample}

    Useful examples are shown below.
    %
\begin{codeexample}[code only]
\pgfplotsset{every extra x tick/.append style={grid=major}}
\pgfplotsset{every extra x tick/.append style={major tick length=0pt}}
\pgfplotsset{every extra x tick/.append style={/pgf/number format=sci subscript}}
\pgfplotsset{
    extra x tick style={
        grid style={
            color=red,
        },
        tickwidth=3mm,
        % the initial 'every tick style' defines a 'line width'.
        % this here redefines it:
        tick style={
            line width=2mm,
        },
    },
}
\end{codeexample}
\end{xystylekey}

\pgfplotsshortxystylekey extra \x\ tick style=every extra \x\ tick\pgfeov

\begin{stylekey}{/pgfplots/extra tick style=\marg{key-value-list}}
    An abbreviation which appends \meta{key-value-list} to
    |every extra x tick|, |every extra y tick| and |every extra z tick|.
\end{stylekey}


\subsection*{Styles for grid lines}

\begin{stylekey}{/pgfplots/every axis grid (initially thin,black!25)}
    Used for each grid line.
\end{stylekey}

\pgfplotsshortstylekey grid style=every axis grid\pgfeov

\begin{stylekey}{/pgfplots/every minor grid (initially empty)}
    Used for each minor grid line, installed after `|every axis grid|'.
\end{stylekey}

\pgfplotsshortstylekey minor grid style=every minor grid\pgfeov

\begin{stylekey}{/pgfplots/every major grid (initially empty)}
    Likewise, for major grid lines.
\end{stylekey}

\pgfplotsshortstylekey major grid style=every major grid\pgfeov

\begin{xystylekey}{/pgfplots/every axis \x\ grid (initially empty)}
    Used for each grid line in either $x$ or $y$ direction.
\end{xystylekey}

\pgfplotsshortxystylekey \x\ grid style=every axis \x\ grid\pgfeov

\begin{xystylekey}{/pgfplots/every minor \x\ grid (initially empty)}
    Used for each minor grid line in either $x$ or $y$ direction.
\end{xystylekey}

\pgfplotsshortxystylekey minor \x\ grid style=every minor \x\ grid\pgfeov

\begin{xystylekey}{/pgfplots/every major \x\ grid (initially empty)}
    Used for each major grid line in either $x$ or $y$ direction.
\end{xystylekey}

\pgfplotsshortxystylekey major \x\ grid style=every major \x\ grid\pgfeov


\subsection*{Styles for error bars}

\begin{stylekey}{/pgfplots/every error bar (initially thin)}
    Installed for every error bar.
\end{stylekey}

\pgfplotsshortstylekey error bars/error bar style=every error bar\pgfeov


\subsection{(Re)Defining Own Styles}
\label{sec:styles:own}

Use |\pgfplotsset{|\meta{style name}|/.style=|\marg{key-value-list}|}| to
create own styles. If \meta{style name} exists already, it will be replaced.
Please note that it is \emph{not} possible to use the \Tikz{} command
|\tikzstyle|\marg{style name}|=[]| in this context.\footnote{This was possible
in a previous version and is still supported for backwards compatibility. But
in some cases, it may not work as expected.}
%
\begin{codeexample}[]
\pgfplotsset{
    my personal style/.style={
        grid=major,
        font=\large,
    },
}
\begin{tikzpicture}
\begin{axis}[my personal style]
    \addplot coordinates {(0,0) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
